"""
    sbak - Primary code library of the ScrollBack game development system.
    
    author:     Bradley K. Harms (a.k.a. TheMusicGuy)
    email:      FearsomeDragonfly@gmail.com
    website:    http://code.google.com/p/scrollback/
    
    This library is the one from Albert, a branch from the main ScrollBack
    project. As such, it is not gaurunteed to be stable--or even compilable--
    at any given time. For a more stable version of the library, check out
    the main (trunk) branch.
    
    To make complete use of this library, the following other Python
    packages must be installed:
    
    * Pygame.
      - Currently required to use sbak at all.
      - http://www.pygame.org/
    * Numpy.
      - Required for tile maps.
      - http://numpy.scipy.org/
      - Also available from the Pygame website (above).
    * json or simplejson.
      - JSON support for Python. Required for loading any type of
        resource other than Pygame surfaces.
      - Installed by default for Python versions >= 2.6, extra package
        (below) needed for Python 2.5 and earlier.
      - http://pypi.python.org/pypi/simplejson/
      
    ~~~ Conventions Used in This Library ~~~
    
    Several conventions are used throughout the code in this library:
    
    * PEP 8:
    
        First and foremost, the code throughout this library tries to adhere
        to the suggestsions of the coding style outlined by PEP 8 as often as
        possible. Any extensions to the library should do the same.
        
        This means, among other things:
        
        * There is a STRICT rule of applying exactly 4 space characters for
          each level of indentation for blocks that are actually recognized by
          the interpreter as actually being blocks. There is more flexibility
          for code that is blocked, but not actually considered to be
          blocked by the interpreter, such as in multi-line statements like
          large dictionary literals or large function/method calls.
        
        * Lines of code should never exceed 80 characters in length. If a piece
          of code cannot be easily expressed inside this limit, it should be
          broken up at the nearest "natural break" from the edge of the 80
          character margin. Use whatever means of breaking the line that
          retains the most clarity of code.
        
        * Docstrings should not exceed 72 characters in width, not counting the
          indentation. This usually works out so that sentences are wrapped at
          the 80 character margin.
        
        See http://www.python.org/dev/peps/pep-0008/ for more details.
    
    * Words surrounded with `backticks`:
    
        Any word or phrase in a docstring or comment that is quoted using
        backticks (such as `these`) refers to a literal name in code or a
        piece of code. For example, `attr` most likely refers to an attribute
        called "attr" of some object. `obj.method()` is the code for calling
        the method called "method" of an object called "obj".
    
    * Names beginning with a single _underscore:
        
        Names that begin with an underscore (ex. `_name`, `_method`) are
        considered to be implementation details and should not be used
        directly by user code, unless there is documentaion for the name
        that explicitly states otherwise.
    
    * Names of functions and methods:
    
        Functions and methods are almost always named with verbs. There is some
        leeway about which kind of verbs are used, but generally they are
        "command" verbs, such as `jump`, `kill`, `find`, etc. Sometimes it is
        necessary (for the purpose of clarity) to give a method a name that is
        a "compound verb", such as `move_towards` or `find_smallest`.
        
        A few functions or methods are not named with verbs, but such names
        tend to indicate that another value must be used in conjunction with
        the attribute. For example, `obj.distance_to` is a method that finds
        the object's distance to someplace, but the name by itself does not
        clearly indicate where "someplace" is. Therefore, it can be inferred
        that `obj.distance_to` requires another component, the most likely way
        of indicating which is to call the attribute as a method.
    
    * Compound words for attribute names:
    
        There is one exception to PEP 8 that is sometimes made in hopes of
        improving clarity:
        
        When an instance of a class has an attribute whose purpose cannot be
        easily expressed with a single word, and that attribute is not a method
        (in the usual sense of a method that is defined in the class of the
        instance), then the attribute may be named with a simple "compund
        word", as in `obj.leftarm` (for "left arm") or `obj.mapname` (for
        "map name"). The rational for this is that having an _underscore in the
        middle of an attribute name makes it look ugly, and tends to make it
        look like a reference to a method even when it is not.
    
    * Base classes:
    
        Nearly every class defined in this library has `sbak.base.Object` in
        its inheritence tree, which in turn is based on Python's `object`
        builtin. Classes which are not based on `sbak.base.Object` are based
        on `object`, `type`, or another one of Python's built-in types.
        
        Effectively what this means is that every class in the library is a
        new-style class. No class should ever be an old-style class.
        
    * Interface classes:
    
        There are several classes throghout the library that are considered
        to be "interfaces." Each such class does not supply any functionality,
        but instead describes the names and semantics of methods (and possibly
        other attributes) that an object must provide in order for it to work
        within some particular system.
        
        It is not usually necessary for a class to inherit from an interface in
        order for the class's objects to be usable in the interface's intended
        system, but if it does then it should override every method of the
        interface with methods of the name and signature. However, the methods
        in an interface class definition should NOT include the `self`
        parameter in the methods' definitions. This helps to make sure that
        each method in the interface is properly overridden: If an attempt is
        made to call a method of an interface-based class and that method was
        not properly overridden, an exception will be raised.
        
        Each interface class should provide docstrings for the class itself as
        well as for each of its methods. The method docstrings should indicate
        (at minimum) how the method may be called, what the method should do,
        and what value the method should return.
        
        The names of interface classes always begin with the uppercase letter
        "I", for example `INode`.
    
    * Other naming conventions:
    
        * Metaclasses always end in the uppercase letter 'M', ex. `ObjectM`
        * Abstract base classes (those which must be subclassed to be used)
          always begin with the word "Abstract", ex. `AbstractObject`
"""

# ~~~ SYSTEM IMPORTS ~~~

import sys
import warnings

# Make sure Pygame is installed...
try:
    import pygame
except ImportError:
    raise ImportError(
    """
    
    Pygame is not intalled on this system. You must install Pygame before you
    can use sbak. Go to http://www.pygame.org to download and install
    Pygame.
    """)

# ~~~ CONSTANTS ~~~

# The "I don't care what ID to use" constant
ID_ANY = "_id_any_"


# ~~~ INTERNAL IMPORTS ~~~

import error
import debug
import base
import geometry
import event
#import video
#import draw
#import ui
#import group
import resman
#import image
#import tilelist
import app
#import entity
import world
    
__all__ = [
    'ID_ANY',

    'error',
#    'debug',
    'base',
    'geometry',
    'event',
    'video',
    'draw',
    'ui',
    'group',
    'image',
    'tilelist',
    'world',
    'resman',
    'entity'
    'app',
    
    'init',
    'quit'
]

def init():
    """ Initializes the ScrollBack.
    
        This initializes all of ScrollBack's modules in the recomended
        order.
    """
    
    # Initialize components
    
    # Video is init'd first because the Pygame manual says that most platforms
    # need pygame.display to be initialized before any other modules.
    #video.init()
    #event.init()
    #ui.init()
    #draw.init()
    #resman.init()
    #entity.init()

def quit():
    """ Quits all modules that should be quit after initialization.
        Also quits Pygame.
        FIXME: Actually, this just quits pygame. No other modules are quit.
    """
    pygame.quit()
